Command Buttons and Events

As promised, we are coming back to events and command buttons. Let me say, even as I broach the subject, that I can not do the entire subject justice in one setting. Understanding events is a mental leap that takes a while to adjust to. This is especially true if your experience has been with top down programming structure, which is what we have been doing so far. Where we want to go is into using more functions of the graphical user interface, which is to say, we want to add some other goodies to our windows other than just graphics.

This time we will be brushing the surface of events as we examine the command button. Just what is a command button? Just other name for a button really - you use them all the time in your windows experience. Here is the quintessential command button - the 'OK' button:

Command buttons are one of a set of objects that can be added to a window to enhance the user environment and allow your program to interact with the user. The group of the objects is referred to as CONTROLS. Liberty Basic discusses these controls to a degree in the helpfile under the heading GUI Programming as seen in this graphic:

A command button control allows the user to initiate an action, interface with the program or respond to a prompt with a single click. The underlying actions of the button are controlled by the programmer. In order to add a command button to a window you must define the button (using Basic code) before the window is opened. This is done with the BUTTON command.

The button command includes in its syntax the window to which the control belongs (specified by its handle). It can only be executed if the window has not yet been opened. If you try to execute a button command AFTER the window has been opened, you will get an error.

I expect that much of the material we are about to cover will be confusing to the new Liberty Basic programmer. The trick now is to do the best you can. We will be reviewing this material again in future installments of this series, and building slowly on the material. For now, you may need to take some of this at face value knowing you will more time to get it later.

The button command (as seen in the helpfile) is quite a mouth full to be sure. Here are the critical part we will be using:

   BUTTON #handle, "label", [branch], corner, x, y

Let's break it down:

BUTTON of course is the command itself. It is not a graphics command as we covered earlier (a command directed at an object); rather it is a pure Liberty Basic command in the same way that PRINT, RND or GOTO are pure Liberty Basic commands. Remember also that it must appear before the command that opens the window specified by the next argument.

The next argument is the #HANDLE. This is the handle of the window on which the command button will appear. It must match the window handle exactly. Remember that you specify handles as you create you program. They are the names by which Liberty Basic refers to the window in your code. As we said earlier, many people like to use the handle "#main" for their main program window. The helpfile makes mention of an optional handle extension, but we will not deal with this added complexity at this time.

LABEL is the next argument. It is a quoted string, and it is the text that will appear on the face of the button. You can pass an empty string, but then no one will know what your button does.

The next argument is the BRANCH. This is the named branch label to which the program execution will be directed if someone clicks your button. It must be surrounded by square brackets. Also, if you specify a branch label here, you also need to actually add the branch label to the body of your program somewhere, or the user will get an error when they click your button.

The next argument is the CORNER ANCHOR. It specifies which corner of the window the button is to be anchored to (which also determines the button's position relative to the anchor point). The valid values for corner are: UL, UR, LL, or LR where UL = upper left, UR = upper right, LL = lower left, and LR = lower right. I have never really seen anyone use a value other than UL, which forces the placement of the control to be determined relative to the upper left corner. Other values cause the placement to be relative to that corner in a less intuitive manner. For now always use UL for this argument and the control placement will conform to that of other controls which do not allow you to "anchor" them to a given corner.

The next two arguments are the X and Y location of the button. If you specified the corner as "UL" then these are distances measured in pixels relative to the upper left corner of the window.

There are two additional optional arguments - they are the width and height of the button in pixels. By default Liberty Basic dynamically sizes the button so that the text label will fit onto the button. The smaller the label, the narrower the button. I like to specify a size for my buttons, as it allows me to get a uniform size and a more standardized look to my windows.

Now that we have examined the component arguments that allow us to use the BUTTON command, let's look at a simple example:

    button #main, "OK", [okClick], UL, 240, 192, 115, 30

This will produce a button labeled "OK" that is 30 pixels high, and 115 pixels wide, located at 240, 192 relative to the upper left corner of the window specified by the handle #main. This button is actually shown a couple pages earlier. I used the code above to produce the button.

That single line of code is not enough to accomplish anything yet - we still need to open the window, as well as write some code to go with our [okClick] label. Lets begin with the window. For our example we will open a simple WINDOW type window. Here is the code:

    nomainwin
    WindowWidth = 370
    WindowHeight = 260
    UpperLeftX = 40
    UpperLeftY = 40

   'here is our button command to create an OK button
    button #main, "OK", [okClick], UL, 240, 192, 115, 30

   'now open the window
    open "GUI Example" for window as #main

That will open a window such as the one shown below:

Although this opens the window, it will not stay open long, because the program will end as soon as the window is open. We need something to make the program stop executing lines of code and just wait for us to do something - like click the OK button.

That command is the WAIT command. We saw it in the previous installment of this series, and we mentioned it above. WAIT is a relative of the INPUT command. It causes the program execution to halt and simply wait for some form of input. Unlike the INPUT statement, it can not receive a value from the user (via a variable assignment). You may not specify a variable to go with the WAIT statement. All it does is wait for the user to click something or interact in some other significant way with the program.

We call this an event. Events happen. When you click a button you trigger an event. When you close a window you trigger an event. When you scroll the window you trigger and event. When you press a key you trigger an event. Not all of these events matter to Liberty Basic, but they are events none the less. The placid window that you see on the screen has a host of things going on behind it in the core of the Windows operating system, and some of those things are the handling of every little event. Once in a while an event (like a click) matters to our program, and Liberty Basic sees those happen and passed them on to our own little program.

Consider our computer waiting for us to do something. It sits idle. Then the user clicks the OK button. Now what? An event has occurred and Liberty Basic passes that event on to our code. We have specified a place in our code where we want the program execution to branch when the event (clicking the OK button) happens. We called it [okClick]. This is actually what we call, in the programming vernacular, an Event Handler. [okClick] begins a section of code that handles the action that we want our program to take when the user clicks the ok button. It is out OK button event handler code.

In the case of our little example we will make it simple - we will pop a notice up onto the screen that says we clicked the OK button. We will use the NOTICE command for this. Remember it? We covered it several issues back. Here is an excerpt from the helpfile to refresh your memory:

Here is our simple event handler code:

   [okClick]
   notice "You clicked the OK button"
   wait

Notice that I added a WAIT command as the last thing the event handler does. This is because we are done handling the event and we need to go back to waiting for more events. We could have used a GOTO command and branched up to the intial WAIT command that follows the creation of the window (and that was the common way of handling things in Liberty Basic coding for a long time), but it is not really necessary.

So, here is all the code so far:

    nomainwin
    WindowWidth = 370
    WindowHeight = 260
    UpperLeftX = 40
    UpperLeftY = 40

   'here is our button command to create an OK button
    button #main, "OK", [okClick], UL, 240, 192, 115, 30

   'now open the window
    open "GUI Example" for window as #main

   wait

   [okClick]
   notice "You clicked the OK button"
   wait

As you will remember from our discussion earlier in this article, there is a special event that occurs when the user clicks the close button in the upper right corner of the window. The event is called the CloseWindow Event and we can "trap" it as we showed you earlier with the following code:

    #main "trapclose [quit]"

That code sends the command TRAPCLOSE to the window AFTER the window has been opened and sets up the trap in the background processing of Liberty Basic (which Liberty Basic manages). It also sets up an event handler labeled [quit]. We will have to add code to handle this event as well.

Please note that although we have set up the event trap and Liberty Basic manages it in the background, events can not be detected by Liberty Basic and brought to the surface so that they can be acted upon unless Liberty Basic is waiting at a WAIT or INPUT statement, or unless the event is queued up and a SCAN statement is executed. (We will not cover the SCAN statement until much later, but you should know it is there.) These three commands are the input mechanisms for the GUI based code. What does it mean? It means that events - like the user click the OK button - do not happen without input and input can not happen unless the program is waiting for input at a WAIT, INPUT or SCAN statement. One of these is required - generally we use the WAIT statement to accomplish this task.

Let's add some code to handle the "trapclose" event:

   [quit]
   close #main
   end

It is always a good idea to clean up. You learned this at home when you we three or four, and again in Kindergarten - Liberty Basic also likes things to be cleaned (and complains if you fail to clean up). In the case of our [quit] event handler code, we want to close the main window (if it is not closed already), then end the execution of the program code with the END statement.

Our final program looks like this:

    nomainwin
    WindowWidth = 370
    WindowHeight = 260
    UpperLeftX = 40
    UpperLeftY = 40

   'here is our button command to create an OK button
    button #main, "OK", [okClick], UL, 240, 192, 115, 30

   'now open the window
    open "GUI Example" for window as #main

    #main "trapclose [quit]"

   wait

   [okClick]
   notice "You clicked the OK button"
   wait

   [quit]
   close #main
   end

We have wrapped up our first plunge into events. It is not a subject easily grasped on first brush, but it is essential to windows programming. There are additional articles on the subject in the newsletter as well as in various tutorials on the Internet. Experiment and play with it. That is how it can go from a strange concept to a friendly fact. We are going to turn to the more practical application of the subjects we looked at in this and the previous installments of this series. A graphical dice roller, which we will develop into a graphical version of Craps in the next installment.

---